---
title: configurations
sidebarTitle: configurations
---

# `prefect.server.database.configurations`

## Classes

### `ConnectionTracker` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A test utility which tracks the connections given out by a connection pool, to
make it easy to see which connections are currently checked out and open.


**Methods:**

#### `clear` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
clear(self) -> None
```

#### `on_close` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_close(self, adapted_connection: AdaptedConnection, connection_record: ConnectionPoolEntry) -> None
```

#### `on_close_detached` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_close_detached(self, adapted_connection: AdaptedConnection) -> None
```

#### `on_connect` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
on_connect(self, adapted_connection: AdaptedConnection, connection_record: ConnectionPoolEntry) -> None
```

#### `track_pool` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
track_pool(self, pool: sa.pool.Pool) -> None
```

### `BaseDatabaseConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Abstract base class used to inject database connection configuration into Prefect.

This configuration is responsible for defining how Prefect REST API creates and manages
database connections and sessions.


**Methods:**

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]
```

Enter a transaction for a session


#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database


#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database


#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Returns a SqlAlchemy engine


#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory


#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.


#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.


### `AsyncPostgresConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L200" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L341" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AsyncGenerator[AsyncSessionTransaction, None]
```

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]
```

Enter a transaction for a session


#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L349" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database


#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database


#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L356" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database


#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database


#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Retrieves an async SQLAlchemy engine.

**Args:**
- `connection_url`: The database connection string.
Defaults to self.connection_url
- `echo`: Whether to echo SQL sent
to the database. Defaults to self.echo
- `timeout`: The database statement timeout, in seconds.
Defaults to self.timeout

**Returns:**
- a SQLAlchemy engine


#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Returns a SqlAlchemy engine


#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L363" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory


#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory


#### `schedule_engine_disposal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L307" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schedule_engine_disposal(self, cache_key: _EngineCacheKey) -> None
```

Dispose of an engine once the event loop is closing.

See caveats at `add_event_loop_shutdown_callback`.

We attempted to lazily clean up old engines when new engines are created, but
if the loop the engine is attached to is already closed then the connections
cannot be cleaned up properly and warnings are displayed.

Engine disposal should only be important when running the application
ephemerally. Notably, this is an issue in our tests where many short-lived event
loops and engines are created which can consume all of the available database
connection slots. Users operating at a scale where connection limits are
encountered should be encouraged to use a standalone server.


#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L331" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

**Args:**
- `engine`: a sqlalchemy engine


#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.


#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.


### `AioSqliteConfiguration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L369" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

**Methods:**

#### `begin_sqlite_conn` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L509" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_sqlite_conn(self, conn: aiosqlite.AsyncAdapt_aiosqlite_connection) -> None
```

#### `begin_sqlite_stmt` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L518" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_sqlite_stmt(self, conn: sa.Connection) -> None
```

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L531" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AsyncGenerator[AsyncSessionTransaction, None]
```

#### `begin_transaction` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L193" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]
```

Enter a transaction for a session


#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L551" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database


#### `create_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L177" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Create the database


#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L558" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database


#### `drop_db` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None
```

Drop the database


#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L372" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Retrieves an async SQLAlchemy engine.

**Args:**
- `connection_url`: The database connection string.
Defaults to self.connection_url
- `echo`: Whether to echo SQL sent
to the database. Defaults to self.echo
- `timeout`: The database statement timeout, in seconds.
Defaults to self.timeout

**Returns:**
- a SQLAlchemy engine


#### `engine` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L167" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
engine(self) -> AsyncEngine
```

Returns a SqlAlchemy engine


#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L565" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory


#### `is_inmemory` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_inmemory(self) -> bool
```

Returns true if database is run in memory


#### `schedule_engine_disposal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L434" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schedule_engine_disposal(self, cache_key: _EngineCacheKey) -> None
```

Dispose of an engine once the event loop is closing.

See caveats at `add_event_loop_shutdown_callback`.

We attempted to lazily clean up old engines when new engines are created, but
if the loop the engine is attached to is already closed then the connections
cannot be cleaned up properly and warnings are displayed.

Engine disposal should only be important when running the application
ephemerally. Notably, this is an issue in our tests where many short-lived event
loops and engines are created which can consume all of the available database
connection slots. Users operating at a scale where connection limits are
encountered should be encouraged to use a standalone server.


#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L542" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.

**Args:**
- `engine`: a sqlalchemy engine


#### `session` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
session(self, engine: AsyncEngine) -> AsyncSession
```

Retrieves a SQLAlchemy session for an engine.


#### `setup_sqlite` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L458" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
setup_sqlite(self, conn: DBAPIConnection, record: ConnectionPoolEntry) -> None
```

Issue PRAGMA statements to SQLITE on connect. PRAGMAs only last for the
duration of the connection. See https://www.sqlite.org/pragma.html for more info.


#### `unique_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
unique_key(self) -> tuple[Hashable, ...]
```

Returns a key used to determine whether to instantiate a new DB interface.

